/*
 * TimingsLog.java    ver   29/nov/2009
 *
 * Copyright (c) 2009 mentalsmash.org
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * The use of the Apache License does not indicate that this project is
 * affiliated with the Apache Software Foundation.
 */
package org.mentalsmash.tazio.commons.timer;

import java.util.List;

/**
 * The <tt>TimingsLog</tt> is a log for keeping measurements about time, for
 * objects.
 * <p>
 * It keeps measurements indexed by an user-provided, free-form key, that should
 * generally represent the object the measurements refer to.
 * </p>
 * 
 * @version 0.0.1 29/nov/2009
 * @author Andrea Reale <andrea.reale@gmail.com>
 * 
 */
public interface TimingsLog {

    /**
     * Add a timing measure for the provided <code>key</code> to the log
     * 
     * @param key
     *            a string representation of the object the measure refers to
     * @param measure
     *            a time measurement in milliseconds
     */
    void addTimingMeasure(String key, long measure);

    /**
     * Returns an Unmodifiable List containing the last timing measures for the
     * object whose string representation is <code>key</code>
     * <p>
     * If no measure for the object represented by <code>key</code> was ever
     * added to the log instance, returns <code>null</code>
     * </p>
     * 
     * @param key
     *            a string representation of the object whose measures are
     *            needed
     * @return an Unmodifiable List containing the last timing measures for the
     *         object whose string representation is <code>key</code>.
     */
    List<Long> getTimeMeasures(String key);

    /**
     * Returns the last timing measurement for the object whose string
     * representation is <code>key</code>.
     * 
     * @param key
     *            a string representation of the object whose measures are
     *            needed
     * @return the value in milliseconds of the last timing measurement for the
     *         object represented by <code>key</code>
     */
    long getLastTimeMeasure(String key);

    /**
     * Returns the maximum timing measurement for the object whose string
     * representation is <code>key</code>.
     * 
     * @param key
     *            a string representation of the object whose measures are
     *            needed
     * @return the value in milliseconds of the maximum timing measurement for
     *         the object represented by <code>key</code>
     */
    long getMaxMeasure(String key);

    /**
     * Returns the minimum timing measurement for the object whose string
     * representation is <code>key</code>.
     * 
     * @param key
     *            a string representation of the object whose measures are
     *            needed
     * @return the value in milliseconds of the minumum timing measurement for
     *         the object represented by <code>key</code>
     */
    long getMinMeasure(String key);

    /**
     * Returns the average of all the observed timing measurements for the
     * object whose string representation is <code>key</code>.
     * 
     * @param key
     *            a string representation of the object whose measures are
     *            needed
     * @return the value in milliseconds of the average of all the observed
     *         timing measurements for the object represented by
     *         <code>key</code>
     */
    double getAvgMeasure(String key);

    /**
     * Returns the standard deviation of all the observed timing measurements
     * for the object whose string representation is <code>key</code>.
     * 
     * @param key
     *            a string representation of the object whose measures are
     *            needed
     * @return the value in milliseconds of the average of all the observed
     *         timing measurements for the object represented by
     *         <code>key</code>
     */
    double getStdDeviation(String key);

    /**
     * Returns an iterable collection of the currently stored keys.
     * 
     * @return an iterable collection of the keys for which there's a timing
     *         recorded in this log
     */
    Iterable<String> getCurrentKeys();

}